React의 `experimental_useFormStatus`로 폼 유효성 검사 마스터하기

폼은 웹 상호작용의 기반입니다. 간단한 뉴스레터 구독부터 복잡한 다단계 금융 애플리케이션에 이르기까지, 폼은 사용자가 애플리케이션과 소통하는 주요 채널입니다. 그러나 수년간 React에서 폼 상태를 관리하는 것은 복잡성, 보일러플레이트 코드, 그리고 의존성에 대한 피로의 원천이었습니다. 우리는 제어 컴포넌트(controlled components)를 다루고, 상태 관리 라이브러리와 씨름하며, 원활하고 직관적인 사용자 경험을 추구하기 위해 수많은 `onChange` 핸들러를 작성해왔습니다.

React 팀은 웹 개발의 이러한 근본적인 측면을 재고해왔고, 이는 React 서버 액션(React Server Actions)을 중심으로 한 새롭고 강력한 패러다임의 도입으로 이어졌습니다. 점진적 향상(progressive enhancement) 원칙에 기반한 이 새로운 모델은 로직을 그것이 속한 곳, 즉 종종 서버에 더 가깝게 이동시킴으로써 폼 처리를 단순화하는 것을 목표로 합니다. 이 클라이언트 사이드 혁명의 중심에는 두 가지 새로운 실험적 훅이 있습니다: `useFormState`와 오늘 논의의 주인공인 `experimental_useFormStatus`입니다.

이 종합 가이드에서는 `experimental_useFormStatus` 훅에 대해 심층적으로 알아볼 것입니다. 단순히 문법만 살펴보는 것이 아니라, 이 훅이 가능하게 하는 사고 모델인 상태 기반 유효성 검사 로직(Status-Based Validation Logic)을 탐구할 것입니다. 이 훅이 어떻게 UI를 폼 상태로부터 분리하고, 보류(pending) 상태 관리를 단순화하며, 서버 액션과 협력하여 자바스크립트가 로드되기 전에도 작동하는 견고하고 접근성이 높으며 성능이 뛰어난 폼을 만드는지 배우게 될 것입니다. React에서 폼을 만드는 것에 대해 알고 있던 모든 것을 다시 생각할 준비를 하십시오.

패러다임의 전환: React 폼의 진화

`useFormStatus`가 가져온 혁신을 완전히 이해하려면, 먼저 React 생태계에서 폼 관리의 여정을 이해해야 합니다. 이 맥락은 이 새로운 접근 방식이 얼마나 우아하게 문제들을 해결하는지 보여줍니다.

과거의 방식: 제어 컴포넌트와 서드파티 라이브러리

수년간 React 폼의 표준 접근 방식은 제어 컴포넌트(controlled component) 패턴이었습니다. 이는 다음을 포함합니다:

• 각 폼 입력의 값을 담기 위해 React 상태 변수(예: `useState`에서 온)를 사용합니다.
• 모든 키 입력 시 상태를 업데이트하기 위해 `onChange` 핸들러를 작성합니다.
• 상태 변수를 입력의 `value` prop으로 다시 전달합니다.

이 방식은 React가 폼 상태를 완전히 제어할 수 있게 해주지만, 상당한 양의 보일러플레이트 코드를 유발합니다. 10개의 필드가 있는 폼의 경우, 10개의 상태 변수와 10개의 핸들러 함수가 필요할 수 있습니다. 유효성 검사, 오류 상태, 제출 상태를 관리하는 것은 훨씬 더 복잡성을 가중시키며, 종종 개발자들이 복잡한 커스텀 훅을 만들거나 포괄적인 서드파티 라이브러리를 사용하게 만듭니다.

Formik이나 React Hook Form과 같은 라이브러리들은 이러한 복잡성을 추상화하여 큰 인기를 얻었습니다. 이들은 상태 관리, 유효성 검사, 성능 최적화를 위한 훌륭한 솔루션을 제공합니다. 그러나 이는 관리해야 할 또 다른 의존성이며, 종종 완전히 클라이언트 측에서 작동하여 프론트엔드와 백엔드 간에 유효성 검사 로직이 중복될 수 있습니다.

새로운 시대: 점진적 향상과 서버 액션

React 서버 액션은 패러다임의 전환을 가져옵니다. 핵심 아이디어는 웹 플랫폼의 기반인 표준 HTML `

` 요소 위에 구축하는 것입니다. 서버 액션이 있는 폼은 고전적인 HTML 폼 제출처럼 작동합니다. 즉, 자바스크립트가 실패하거나 비활성화된 경우에도 완벽하게 기능할 수 있습니다. 이것이 바로 점진적 향상(progressive enhancement)의 본질입니다.

자바스크립트가 로드되면 React는 폼의 제출 프로세스를 가로채 전체 페이지 새로고침을 방지하고 서버 액션을 비동기적으로 실행합니다. 이는 우리에게 두 세계의 장점을 모두 제공합니다: 서버 렌더링 애플리케이션의 복원력과 단일 페이지 애플리케이션(SPA)의 풍부하고 상호작용적인 경험입니다.

이 모델은 비즈니스 로직과 유효성 검사의 진실 공급원(source of truth)을 서버(또는 서버와 유사한 환경)로 다시 이동시킵니다. 클라이언트 사이드 코드는 더 단순해지며, 주로 해당 서버 통신의 *상태*에 따라 UI를 렌더링하는 데 관심을 둡니다. 이것이 바로 `useFormStatus`가 활약하는 지점입니다.

내부 살펴보기: `experimental_useFormStatus`란 무엇인가?

`experimental_useFormStatus` 훅은 부모 `` 요소의 마지막 제출에 대한 정보를 제공하도록 설계된 클라이언트 사이드 도구입니다. 이것은 컴포넌트가 어떠한 prop도 전달받지 않고도 폼의 제출 상태에 대해 알아야 할 모든 것을 알려주는 읽기 전용 훅입니다.

핵심 기능

큰 폼 안에 있는 제출 버튼을 상상해보세요. 이 버튼은 폼이 제출 중이라는 것을 어떻게 알 수 있을까요? 전통적으로는 `isSubmitting`과 같은 상태 변수를 여러 컴포넌트 계층을 통해 전달해야 했습니다(prop drilling). `useFormStatus`를 사용하면 버튼 컴포넌트가 이 정보를 스스로 알아낼 수 있습니다.

이 훅은 반드시 `` 요소 *내부*에서 렌더링되는 컴포넌트에서 호출되어야 합니다. 그러면 해당 특정 폼의 생명주기에 대한 상태 정보를 제공합니다.

`useFormStatus` 훅의 구조

`const status = useFormStatus()`를 호출하면 다음과 같은 주요 속성을 가진 객체를 받게 됩니다:

• `pending` (boolean): 가장 자주 사용되는 속성입니다. 부모 폼이 현재 제출 중이면 `true`이고 그렇지 않으면 `false`입니다. 버튼을 비활성화하거나, 로딩 스피너를 보여주거나, 보류 상태를 스타일링하는 데 완벽합니다.
• `data` (FormData): `FormData` 인터페이스를 구현하는 객체입니다. 폼과 함께 제출된 데이터를 포함합니다. 이는 낙관적 UI 업데이트(optimistic UI updates)를 구현하는 데 매우 유용합니다. 예를 들어, 사용자가 댓글을 제출하자마자 서버가 생성을 확인하기 전에도 즉시 목록에 표시하는 경우입니다.
• `method` (string): 폼 제출에 사용된 HTTP 메서드('get' 또는 'post')입니다.
• `action` (function): 제출 중에 호출된 서버 액션 함수에 대한 참조입니다.

황금률: ``의 자식이어야 합니다

기억해야 할 중요한 규칙은 `useFormStatus`를 사용하는 컴포넌트는 추적하려는 `` 요소의 자식으로 렌더링되어야 한다는 것입니다. 폼의 컨텍스트에 접근해야 하므로, `` 태그 자체를 렌더링하는 동일한 컴포넌트에 있을 수 없습니다. 이것이 거의 항상 ``과 같은 컴포넌트가 `useFormStatus` 로직을 담기 위해 별도로 생성되는 이유입니다.

간단한 예제: 스마트 제출 버튼

가장 일반적인 사용 사례를 실제로 살펴보겠습니다. 표준 `` 대신, 폼의 제출 상태를 인지하는 컴포넌트를 만들 것입니다.

파일: SubmitButton.js

import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton() { const { pending } = useFormStatus(); return (

{pending ? '제출 중...' : '가입하기'} ); }

파일: SignUpForm.js

import { SubmitButton } from './SubmitButton'; import { signUpAction } from './actions'; // 서버 액션 export function SignUpForm() { return ( 이메일:
); }

이 예제에서 `SubmitButton`은 완전히 독립적입니다. 어떠한 prop도 받지 않습니다. `useFormStatus`를 사용하여 `SignUpForm`이 보류 상태일 때를 파악하고 자동으로 자신을 비활성화하고 텍스트를 변경합니다. 이는 컴포넌트를 분리하고 재사용 가능한, 폼을 인지하는 컴포넌트를 만드는 강력한 패턴입니다.

문제의 핵심: 상태 기반 유효성 검사 로직

이제 핵심 개념에 도달했습니다. `useFormStatus`는 단지 로딩 상태만을 위한 것이 아니라, 유효성 검사에 대한 다른 사고방식을 가능하게 하는 핵심 요소입니다.

"상태 검증" 정의하기

상태 기반 유효성 검사는 유효성 검사 피드백이 주로 폼 제출 시도에 대한 응답으로 사용자에게 전달되는 패턴입니다. 모든 키 입력 시(`onChange`) 또는 사용자가 필드를 떠날 때(`onBlur`) 유효성을 검사하는 대신, 주요 유효성 검사 로직은 사용자가 폼을 제출할 때 실행됩니다. 이 제출의 결과, 즉 그 *상태*(예: 성공, 유효성 검사 오류, 서버 오류)가 UI를 업데이트하는 데 사용됩니다.

이 접근 방식은 React 서버 액션과 완벽하게 일치합니다. 서버 액션은 유효성 검사에 대한 단일 진실 공급원(single source of truth)이 됩니다. 폼 데이터를 받아 비즈니스 규칙(예: "이 이메일이 이미 사용 중인가?")에 따라 유효성을 검사하고 결과를 나타내는 구조화된 상태 객체를 반환합니다.

그 파트너의 역할: `experimental_useFormState`

`useFormStatus`는 *무슨 일이* 일어나고 있는지(보류 중) 알려주지만, 무슨 일이 일어났는지에 대한 *결과*는 알려주지 않습니다. 이를 위해 자매 훅인 `experimental_useFormState`가 필요합니다.

`useFormState`는 폼 액션의 결과에 따라 상태를 업데이트하도록 설계된 훅입니다. 액션 함수와 초기 상태를 인수로 받아 새로운 상태와 폼에 전달할 래핑된 액션 함수를 반환합니다.

const [state, formAction] = useFormState(myAction, initialState);

• `state`: 이것은 `myAction`의 마지막 실행으로부터의 반환 값을 포함합니다. 여기서 오류 메시지를 얻게 될 것입니다.
• `formAction`: 이것은 `
  `의 `action` prop에 전달해야 하는 새로운 버전의 액션입니다. 이것이 호출되면 원래 액션을 트리거하고 `state`를 업데이트합니다.

결합된 워크플로: 클릭부터 피드백까지

`useFormState`와 `useFormStatus`가 함께 작동하여 완전한 유효성 검사 루프를 만드는 방법은 다음과 같습니다:

1. 초기 렌더링: 폼은 `useFormState`에서 제공하는 초기 상태로 렌더링됩니다. 오류는 표시되지 않습니다.
2. 사용자 제출: 사용자가 제출 버튼을 클릭합니다.
3. 보류 상태: 제출 버튼의 `useFormStatus` 훅이 즉시 `pending: true`를 보고합니다. 버튼은 비활성화되고 로딩 메시지를 표시합니다.
4. 액션 실행: (`useFormState`에 의해 래핑된) 서버 액션이 폼 데이터와 함께 실행됩니다. 유효성 검사를 수행합니다.
5. 액션 반환: 액션이 유효성 검사에 실패하고 상태 객체를 반환합니다. 예를 들어:
   `{ message: "유효성 검사에 실패했습니다", errors: { email: "이 이메일은 이미 사용 중입니다." } }`
6. 상태 업데이트: `useFormState`가 이 반환 값을 받아 `state` 변수를 업데이트합니다. 이는 폼 컴포넌트의 재렌더링을 트리거합니다.
7. UI 피드백: 폼이 재렌더링됩니다. `useFormStatus`의 `pending` 상태는 `false`가 됩니다. 이제 컴포넌트는 `state.errors.email`을 읽고 이메일 입력 필드 옆에 오류 메시지를 표시할 수 있습니다.

이 전체 흐름은 제출 상태와 결과에 의해 전적으로 구동되는, 명확하고 서버가 권위를 갖는 피드백을 사용자에게 제공합니다.

실전 마스터클래스: 다중 필드 회원가입 폼 만들기

이러한 개념들을 실제 운영 수준의 완전한 회원가입 폼을 구축하여 확고히 해봅시다. 유효성 검사를 위해 서버 액션을 사용하고, 훌륭한 사용자 경험을 만들기 위해 `useFormState`와 `useFormStatus`를 모두 사용할 것입니다.

1단계: 유효성 검사를 포함한 서버 액션 정의하기

먼저, 서버 액션이 필요합니다. 견고한 유효성 검사를 위해 인기 있는 라이브러리인 Zod를 사용하겠습니다. 이 액션은 별도의 파일에 위치하며, Next.js와 같은 프레임워크를 사용하는 경우 `'use server';` 지시문으로 표시됩니다.

파일: actions/authActions.js

'use server'; import { z } from 'zod'; // 유효성 검사 스키마 정의 const registerSchema = z.object({ username: z.string().min(3, '사용자 이름은 3자 이상이어야 합니다.'), email: z.string().email('유효한 이메일 주소를 입력해주세요.'), password: z.string().min(8, '비밀번호는 8자 이상이어야 합니다.'), }); // 폼의 초기 상태 정의 export const initialState = { message: '', errors: {}, }; export async function registerUser(prevState, formData) { // 1. 폼 데이터 유효성 검사 const validatedFields = registerSchema.safeParse( Object.fromEntries(formData.entries()) ); // 2. 유효성 검사 실패 시, 오류 반환 if (!validatedFields.success) { return { message: '유효성 검사에 실패했습니다. 필드를 확인해주세요.', errors: validatedFields.error.flatten().fieldErrors, }; } // 3. (시뮬레이션) 데이터베이스에 사용자가 이미 존재하는지 확인 // 실제 앱에서는 여기서 데이터베이스를 쿼리합니다. if (validatedFields.data.email === 'user@example.com') { return { message: '가입에 실패했습니다.', errors: { email: ['이미 등록된 이메일입니다.'] }, }; } // 4. (시뮬레이션) 사용자 생성 console.log('사용자 생성 중:', validatedFields.data); // 5. 성공 상태 반환 // 실제 앱에서는 'next/navigation'의 `redirect()`를 사용하여 여기서 리디렉션할 수 있습니다. return { message: '사용자가 성공적으로 등록되었습니다!', errors: {}, }; }

이 서버 액션은 우리 폼의 두뇌입니다. 이것은 독립적이고 안전하며 성공 및 오류 상태에 대한 명확한 데이터 구조를 제공합니다.

2단계: 재사용 가능하고 상태를 인지하는 컴포넌트 구축하기

메인 폼 컴포넌트를 깔끔하게 유지하기 위해, 입력과 제출 버튼을 위한 전용 컴포넌트를 만들 것입니다.

파일: components/SubmitButton.js

'use client'; import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton({ label }) { const { pending } = useFormStatus(); return ( {pending ? '처리 중...' : label} ); }

`aria-disabled={pending}` 사용에 주목하세요. 이것은 스크린 리더가 비활성화 상태를 정확하게 알리도록 보장하는 중요한 접근성 실천 방법입니다.

3단계: `useFormState`로 메인 폼 조립하기

이제 메인 폼 컴포넌트에서 모든 것을 통합해 보겠습니다. `useFormState`를 사용하여 UI를 `registerUser` 액션에 연결할 것입니다.

파일: components/RegistrationForm.js

'use client'; import { experimental_useFormState as useFormState } from 'react-dom'; import { registerUser, initialState } from '../actions/authActions'; import { SubmitButton } from './SubmitButton'; export function RegistrationForm() { const [state, formAction] = useFormState(registerUser, initialState); return (

회원가입

{state?.message && !state.errors &&

{state.message}

} {state?.message && state.errors &&

{state.message}

}

사용자 이름 {state?.errors?.username && (

{state.errors.username[0]}

)}

이메일 {state?.errors?.email && (

{state.errors.email[0]}

)}

비밀번호 {state?.errors?.password && (

{state.errors.password[0]}

)}

); }

이 컴포넌트는 이제 선언적이고 깔끔합니다. `useFormState`가 제공하는 `state` 객체 외에는 어떤 상태도 직접 관리하지 않습니다. 그 유일한 임무는 해당 상태를 기반으로 UI를 렌더링하는 것입니다. 버튼 비활성화 로직은 `SubmitButton`에 캡슐화되어 있으며, 모든 유효성 검사 로직은 `authActions.js`에 있습니다. 이러한 관심사의 분리는 유지보수성 측면에서 큰 이점입니다.

고급 기술 및 전문적인 모범 사례

기본 패턴이 강력하지만, 실제 애플리케이션에서는 종종 더 많은 미묘함이 필요합니다. 몇 가지 고급 기술을 살펴보겠습니다.

하이브리드 접근법: 즉각적인 검증과 제출 후 검증의 결합

상태 기반 유효성 검사는 서버 측 확인에 훌륭하지만, 사용자의 이메일이 유효하지 않다고 알리기 위해 네트워크 왕복을 기다리는 것은 느릴 수 있습니다. 하이브리드 접근법이 종종 최선입니다:

• HTML5 유효성 검사 사용: 기본을 잊지 마세요! `required`, `type="email"`, `minLength`, `pattern`과 같은 속성은 비용 없이 즉각적인 브라우저 네이티브 피드백을 제공합니다.
• 가벼운 클라이언트 측 유효성 검사: 순전히 외관상 또는 형식 확인(예: 비밀번호 강도 표시기)을 위해 최소한의 `useState`와 `onChange` 핸들러를 여전히 사용할 수 있습니다.
• 서버 측 권한: 클라이언트에서 수행할 수 없는 가장 중요하고 비즈니스 로직에 기반한 유효성 검사(예: 고유한 사용자 이름 확인, 데이터베이스 기록에 대한 유효성 검사)는 서버 액션에 맡깁니다.

이는 단순한 오류에 대한 즉각적인 피드백과 복잡한 규칙에 대한 권위 있는 유효성 검사라는 두 세계의 장점을 모두 제공합니다.

접근성 (A11y): 모두를 위한 폼 만들기

접근성은 타협할 수 없는 부분입니다. 상태 기반 유효성 검사를 구현할 때 다음 사항을 명심하세요:

• 오류 알림: 예제에서는 오류 메시지 컨테이너에 `aria-live="polite"`를 사용했습니다. 이는 스크린 리더에게 사용자의 현재 흐름을 방해하지 않으면서 오류 메시지가 나타나는 즉시 알리도록 지시합니다.
• 오류와 입력 연관시키기: 더 견고한 연결을 위해 `aria-describedby` 속성을 사용하세요. 입력은 오류 메시지 컨테이너의 ID를 가리켜 프로그래밍 방식의 링크를 만들 수 있습니다.
• 포커스 관리: 오류가 있는 제출 후, 첫 번째 유효하지 않은 필드로 프로그래밍 방식으로 포커스를 이동하는 것을 고려하세요. 이는 사용자가 무엇이 잘못되었는지 찾는 수고를 덜어줍니다.

`useFormStatus`의 `data` 속성을 이용한 낙관적 UI

사용자가 댓글을 게시하는 소셜 미디어 앱을 상상해보세요. 1초 동안 스피너를 보여주는 대신, 앱이 즉각적으로 느껴지게 만들 수 있습니다. `useFormStatus`의 `data` 속성은 이를 위해 완벽합니다.

폼이 제출되면 `pending`은 true가 되고 `data`는 제출된 `FormData`로 채워집니다. 이 `data`를 사용하여 즉시 새 댓글을 임시적인 '보류' 시각적 상태로 렌더링할 수 있습니다. 서버 액션이 성공하면 보류 중인 댓글을 서버에서 온 최종 데이터로 교체합니다. 실패하면 보류 중인 댓글을 제거하고 오류를 표시할 수 있습니다. 이는 애플리케이션이 놀랍도록 반응적으로 느껴지게 만듭니다.

"실험적(Experimental)" 기능 다루기

`experimental_useFormStatus`와 `experimental_useFormState`의 "실험적" 접두사를 다루는 것이 중요합니다.

"실험적"이 실제로 의미하는 것

React가 API를 실험적으로 표시할 때, 이는 다음을 의미합니다:

• API가 변경될 수 있음: 이름, 인수 또는 반환 값이 표준 시맨틱 버저닝(SemVer)을 따르지 않고 향후 React 릴리스에서 변경될 수 있습니다.
• 버그가 있을 수 있음: 새로운 기능으로서, 아직 완전히 이해되거나 해결되지 않은 엣지 케이스가 있을 수 있습니다.
• 문서가 부족할 수 있음: 핵심 개념은 문서화되어 있지만, 고급 패턴에 대한 상세한 가이드는 아직 발전 중일 수 있습니다.

언제 도입하고 언제 기다려야 하는가

그렇다면, 프로젝트에서 사용해야 할까요? 대답은 상황에 따라 다릅니다:

• 적합한 경우: 개인 프로젝트, 내부 도구, 스타트업 또는 잠재적인 API 변경 관리에 익숙한 팀. Next.js와 같은 프레임워크(이 기능들을 App Router에 통합함) 내에서 사용하는 것은 일반적으로 더 안전한 선택입니다. 프레임워크가 일부 변경 사항을 추상화하는 데 도움이 될 수 있기 때문입니다.
• 주의해서 사용해야 할 경우: 대규모 엔터프라이즈 애플리케이션, 미션 크리티컬 시스템 또는 API 안정성이 가장 중요한 장기 유지보수 계약이 있는 프로젝트. 이러한 경우, 훅이 안정적인 API로 승격될 때까지 기다리는 것이 현명할 수 있습니다.

이러한 훅의 안정화에 관한 발표를 위해 항상 공식 React 블로그와 문서를 주시하세요.

결론: React 폼의 미래

`experimental_useFormStatus`와 관련 API의 도입은 새로운 도구 그 이상입니다. 이는 우리가 React로 상호작용적인 경험을 구축하는 방식에 대한 철학적 전환을 나타냅니다. 웹 플랫폼의 기반을 수용하고 상태 저장 로직을 서버에 함께 배치함으로써, 우리는 더 단순하고, 더 복원력 있으며, 종종 더 성능이 좋은 애플리케이션을 구축할 수 있습니다.

우리는 `useFormStatus`가 컴포넌트가 폼 제출의 생명주기에 반응하는 깔끔하고 분리된 방법을 어떻게 제공하는지 보았습니다. 이는 보류 상태에 대한 prop drilling을 제거하고 스마트한 `SubmitButton`과 같은 우아하고 독립적인 UI 컴포넌트를 가능하게 합니다. `useFormState`와 결합될 때, 이는 서버가 궁극적인 권위자이고 클라이언트의 주요 책임은 서버 액션이 반환한 상태를 렌더링하는 것인 상태 기반 유효성 검사의 강력한 패턴을 열어줍니다.

"실험적" 태그는 어느 정도의 주의를 요하지만, 방향은 분명합니다. React 폼의 미래는 점진적 향상, 단순화된 상태 관리, 그리고 클라이언트와 서버 로직 간의 강력하고 원활한 통합의 시대입니다. 오늘 이 새로운 훅들을 마스터함으로써, 여러분은 단순히 새로운 API를 배우는 것이 아니라, React를 사용한 차세대 웹 애플리케이션 개발을 준비하는 것입니다.